home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / g_man / cat3 / standard / stencil.z / stencil
Encoding:
Text File  |  2002-10-03  |  10.2 KB  |  199 lines
  1.  
  2.  
  3.  
  4. sssstttteeeennnncccciiiillll((((3333GGGG))))                                                        sssstttteeeennnncccciiiillll((((3333GGGG))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      sssstttteeeennnncccciiiillll - alter the operating parameters of the stencil
  10.  
  11. CCCC SSSSPPPPEEEECCCCIIIIFFFFIIIICCCCAAAATTTTIIIIOOOONNNN
  12.      vvvvooooiiiidddd sssstttteeeennnncccciiiillll((((eeeennnnaaaabbbblllleeee,,,, rrrreeeeffff,,,, ffffuuuunnnncccc,,,, mmmmaaaasssskkkk,,,, ffffaaaaiiiillll,,,, ppppaaaassssssss,,,, zzzzppppaaaassssssss))))
  13.      lllloooonnnngggg eeeennnnaaaabbbblllleeee;;;;
  14.      uuuunnnnssssiiiiggggnnnneeeedddd lllloooonnnngggg rrrreeeeffff;;;;
  15.      lllloooonnnngggg ffffuuuunnnncccc;;;;
  16.      uuuunnnnssssiiiiggggnnnneeeedddd lllloooonnnngggg mmmmaaaasssskkkk;;;;
  17.      lllloooonnnngggg ffffaaaaiiiillll,,,, ppppaaaassssssss,,,, zzzzppppaaaassssssss;;;;
  18.  
  19. PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRRSSSS
  20.      _e_n_a_b_l_e   expects either TTTTRRRRUUUUEEEE or FFFFAAAALLLLSSSSEEEE, enabling or disabling stencil
  21.               operation.  When stencil operation is disabled (the default),
  22.               the values of the subsequent six parameters are ignored,
  23.  
  24.      _r_e_f      expects a reference value used by the stencil compare function.
  25.  
  26.      _f_u_n_c     expects one of eight flags specifying the stencil comparison
  27.               function.  These flags are SSSSFFFF____NNNNEEEEVVVVEEEERRRR, SSSSFFFF____LLLLEEEESSSSSSSS, SSSSFFFF____EEEEQQQQUUUUAAAALLLL,
  28.               SSSSFFFF____LLLLEEEEQQQQUUUUAAAALLLL, SSSSFFFF____GGGGRRRREEEEAAAATTTTEEEERRRR, SSSSFFFF____NNNNOOOOTTTTEEEEQQQQUUUUAAAALLLL, SSSSFFFF____GGGGEEEEQQQQUUUUAAAALLLL, and SSSSFFFF____AAAALLLLWWWWAAAAYYYYSSSS.
  29.  
  30.      _m_a_s_k     expects a mask specifying which stencil bitplanes are
  31.               significant during the comparison operation.
  32.  
  33.      _f_a_i_l     expects one of six flags indicating which stencil operation
  34.               should be performed should the stencil test fail.  The values
  35.               are SSSSTTTT____KKKKEEEEEEEEPPPP, SSSSTTTT____ZZZZEEEERRRROOOO, SSSSTTTT____RRRREEEEPPPPLLLLAAAACCCCEEEE, SSSSTTTT____IIIINNNNCCCCRRRR, SSSSTTTT____DDDDEEEECCCCRRRR, and
  36.               SSSSTTTT____IIIINNNNVVVVEEEERRRRTTTT.
  37.  
  38.      _p_a_s_s     expects one of six flags indicating which stencil operation
  39.               should be performed should the stencil test pass, and the z-
  40.               buffer test (if z-buffering is enabled) fail.  The values are
  41.               SSSSTTTT____KKKKEEEEEEEEPPPP, SSSSTTTT____ZZZZEEEERRRROOOO, SSSSTTTT____RRRREEEEPPPPLLLLAAAACCCCEEEE, SSSSTTTT____IIIINNNNCCCCRRRR, SSSSTTTT____DDDDEEEECCCCRRRR, and SSSSTTTT____IIIINNNNVVVVEEEERRRRTTTT.
  42.  
  43.      _z_p_a_s_s    expects one of six flags indicating which stencil operation
  44.               should be performed should the stencil and z-buffer tests pass.
  45.               Its value is not significant when the z-buffer is not enabled.
  46.               The values are SSSSTTTT____KKKKEEEEEEEEPPPP, SSSSTTTT____ZZZZEEEERRRROOOO, SSSSTTTT____RRRREEEEPPPPLLLLAAAACCCCEEEE, SSSSTTTT____IIIINNNNCCCCRRRR, SSSSTTTT____DDDDEEEECCCCRRRR,
  47.               and SSSSTTTT____IIIINNNNVVVVEEEERRRRTTTT.
  48.  
  49. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  50.      sssstttteeeennnncccciiiillll operates as a superior z-buffer test with a different algorithm.
  51.      When sssstttteeeennnncccciiiillll is enabled, each pixel write first tests the stencil
  52.      bitplanes.  Both the color and z-buffer bitplane writes, as well as the
  53.      write of the stencil bitplanes, are conditioned by the stencil test.
  54.      sssstttteeeennnncccciiiillll operation can be enabled only if stencil bitplanes are present
  55.      (see sssstttteeeennnnssssiiiizzzzeeee).  Stencil bitplanes are present only in the normal
  56.      framebuffer, so sssstttteeeennnncccciiiillll should be called only while draw mode is
  57.      NNNNOOOORRRRMMMMAAAALLLLDDDDRRRRAAAAWWWW.
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. sssstttteeeennnncccciiiillll((((3333GGGG))))                                                        sssstttteeeennnncccciiiillll((((3333GGGG))))
  71.  
  72.  
  73.  
  74.      When the z-buffer is enabled, three test cases are distinguished:
  75.  
  76.      _f_a_i_l     Stencil test fails.
  77.  
  78.      _p_a_s_s     Stencil test passes, but z-buffer test fails.
  79.  
  80.      _z_p_a_s_s    Stencil test passes, and z-buffer test passes.
  81.  
  82.      (When the z-buffer is not enabled, only cases _f_a_i_l and _p_a_s_s are
  83.      considered.)  In all three cases the stencil bitplanes are updated with a
  84.      potentially new value.  This value is a function of the case.  The user
  85.      specifies, for each case, which of six possible values will be used:
  86.  
  87.      SSSSTTTT____KKKKEEEEEEEEPPPP       Keep the current value (no change).
  88.  
  89.      SSSSTTTT____ZZZZEEEERRRROOOO       Replace with zero.
  90.  
  91.      SSSSTTTT____RRRREEEEPPPPLLLLAAAACCCCEEEE    Replace with the reference value.
  92.  
  93.      SSSSTTTT____IIIINNNNCCCCRRRR       Increment by one (clamp to max).
  94.  
  95.      SSSSTTTT____DDDDEEEECCCCRRRR       Decrement by one (clamp to zero).
  96.  
  97.      SSSSTTTT____IIIINNNNVVVVEEEERRRRTTTT     Invert all bits.
  98.  
  99.      Arguments _f_a_i_l, _p_a_s_s, and _z_p_a_s_s are each specified as one of SSSSTTTT____KKKKEEEEEEEEPPPP,
  100.      SSSSTTTT____ZZZZEEEERRRROOOO, SSSSTTTT____RRRREEEEPPPPLLLLAAAACCCCEEEE, SSSSTTTT____IIIINNNNCCCCRRRR, SSSSTTTT____DDDDEEEECCCCRRRR, and SSSSTTTT____IIIINNNNVVVVEEEERRRRTTTT.
  101.  
  102.      _r_e_f is the reference value used by the function that determines whether
  103.      the stencil test passes or fails.  _f_u_n_c specifies the comparison between
  104.      ref and the current stencil plane value.  This comparison function is
  105.      specified with the flags:
  106.  
  107.      SSSSFFFF____NNNNEEEEVVVVEEEERRRR       Never pass.
  108.  
  109.      SSSSFFFF____LLLLEEEESSSSSSSS        Pass if _r_e_f is less than _s_t_e_n_c_i_l.
  110.  
  111.      SSSSFFFF____LLLLEEEEQQQQUUUUAAAALLLL      Pass if _r_e_f is less than or equal to _s_t_e_n_c_i_l.
  112.  
  113.      SSSSFFFF____EEEEQQQQUUUUAAAALLLL       Pass if _r_e_f is equal to _s_t_e_n_c_i_l.
  114.  
  115.      SSSSFFFF____GGGGRRRREEEEAAAATTTTEEEERRRR     Pass if _r_e_f is greater than _s_t_e_n_c_i_l.
  116.  
  117.      SSSSFFFF____GGGGEEEEQQQQUUUUAAAALLLL      Pass if _r_e_f is greater than or equal to _s_t_e_n_c_i_l.
  118.  
  119.      SSSSFFFF____NNNNOOOOTTTTEEEEQQQQUUUUAAAALLLL    Pass if _r_e_f is not equal to _s_t_e_n_c_i_l.
  120.  
  121.      SSSSFFFF____AAAALLLLWWWWAAAAYYYYSSSS      Always pass.
  122.  
  123.      The stencil bitplanes are treated as an unsigned integer of _p_l_a_n_e_s bits,
  124.      where _p_l_a_n_e_s is the value passed to sssstttteeeennnnssssiiiizzzzeeee to allocate the stencil
  125.      buffer.
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. sssstttteeeennnncccciiiillll((((3333GGGG))))                                                        sssstttteeeennnncccciiiillll((((3333GGGG))))
  137.  
  138.  
  139.  
  140.      _m_a_s_k is a field that specifies which stencil bitplanes are to be
  141.      considered by the test.  It does not affect which bitplanes are updated.
  142.  
  143.      If the z-buffer is enabled, color and depth fields are drawn only in the
  144.      _z_p_a_s_s case (both the stencil and depth tests pass).  If the z-buffer is
  145.      not enabled, color is drawn only in the _p_a_s_s case.  The _z_p_a_s_s case is
  146.      ignored.
  147.  
  148. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  149.      drawmode, polymode, sclear, stensize, swritemask, zbuffer
  150.  
  151. NNNNOOOOTTTTEEEESSSS
  152.      IRIS-4D G, GT, and GTX models, as well as the Personal Iris, Iris Indy,
  153.      Iris Indigo Entry, and Indigo XL, do not support sssstttteeeennnncccciiiillll.  Use ggggeeeettttggggddddeeeesssscccc
  154.      to determine whether sssstttteeeennnncccciiiillll is supported.
  155.  
  156.      sssstttteeeennnncccciiiillll is supported only in the normal framebuffer, and is therefore
  157.      effective only while draw mode is NNNNOOOORRRRMMMMAAAALLLLDDDDRRRRAAAAWWWW.
  158.  
  159. BBBBUUUUGGGGSSSS
  160.      IRIS-4D VGX models do not support stencil operation when aaaaffffuuuunnnnccccttttiiiioooonnnn is
  161.      enabled.
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.